---
title: Astro 업그레이드
description: Astro를 업그레이드하는 방법 알아보기
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Version from '~/components/Version.astro';


이 가이드에서는 Astro 버전 및 관련 종속성을 업데이트하는 방법, 한 버전에서 다음 버전으로 변경된 내용을 알아보는 방법, Astro의 버전 관리 시스템 및 해당 문서 업데이트를 이해하는 방법에 대해 설명합니다.

## 달라진 점은 무엇인가요?
현재 Astro의 최신 릴리스는 <Version pkgName="astro" /> 입니다.

모든 변경사항의 전체 목록은 [Astro의 변경 로그](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md)에서, 새로운 [주버전 버전](#주버전-변경)으로 업그레이드하는 데 필요한 중요한 지침은 [업그레이드 가이드](#업그레이드-가이드)에서 확인할 수 있습니다.


## 최신 버전으로 업그레이드

사용하는 패키지 관리자를 통해 명령 한 번으로 프로젝트의 Astro 버전과 모든 공식 통합을 최신 버전으로 업데이트하세요:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드하기
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드하기
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드하기
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>


### 수동으로 업그레이드

Astro 및 통합을 수동으로 각각 현재 버전으로 업데이트하려면 사용하는 패키지 관리자에 적합한 명령을 사용하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 예시: React 및 Tailwind 통합을 포함해서 Astro를 업그레이드 합니다
  npm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 예시: React 및 Tailwind 통합을 포함해서 Astro를 업그레이드 합니다
  pnpm add astro@latest @astrojs/react@latest @astrojs/tailwind@latest
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 예시: React 및 Tailwind 통합을 포함해서 Astro를 업그레이드 합니다
  yarn add astro@latest @astrojs/react@latest @astrojs/tailwind@latest
  ```
  </Fragment>
</PackageManagerTabs>

### 특정 버전 설치

특정 [Astro 버전](https://www.npmjs.com/package/astro?activeTab=versions) 또는 통합 기능을 설치하려면 사용하는 패키지 관리자에 맞는 명령을 사용하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
</PackageManagerTabs>


## 문서 업데이트

이 문서는 [부버전 릴리스](#부버전-변경) 및 [주버전 버전 릴리스](#주버전-변경)가 있을 때마다 업데이트됩니다. 새로운 기능이 추가되거나, 기존 사용법이 변경되면, 문서가 업데이트되어 Astro의 **현재 동작**을 반영합니다. 프로젝트가 업데이트되지 않은 경우, 일부 동작이 최신 문서와 일치하지 않을 수 있습니다.

새로운 기능은 추가된 특정 버전 번호와 함께 문서에 추가됩니다. 즉, 최신 버전의 Astro로 업데이트하지 않은 경우 일부 문서화된 기능을 사용하지 못할 수 있습니다. 새로운 기능을 사용하기 전에 항상 `Added in:` 버전 번호를 확인하고 프로젝트가 업데이트되었는지 확인하세요!

최신 주버전 버전의 Astro로 업그레이드하지 않은 경우, Astro 문서와 프로젝트의 동작 간에 상당한 차이가 발생할 수 있습니다. 가능한 한 빨리 현재 주버전 버전의 Astro로 업그레이드할 것을 강력히 권장합니다. 이전 버전의 코드와 문서는 모두 지원되지 않습니다.

### 업그레이드 가이드

모든 [주버전 버전 릴리스](#주버전-변경) 이후에는 중요한 변경 사항에 대한 정보와 프로젝트 코드 업그레이드 지침이 포함된 **업그레이드 가이드**를 확인할 수 있습니다.

Astro의 기본 문서 페이지는 항상 **최신 출시된 버전의 Astro에 대해 정확합니다**. 이전 버전의 작동 방식을 설명하거나 비교하지 않으며, 업데이트되거나 변경된 동작을 강조하지도 않습니다.

아래 업그레이드 가이드에서 새 버전과 이전 버전을 비교하여 변경 사항에 대한 설명을 확인하세요. 업그레이드 가이드에는 변경 사항, 사용 중단, 기능 제거 및 대체, 업데이트된 사용 안내 등 코드를 변경해야 할 수 있는 모든 내용이 포함되어 있습니다. Astro의 각 변경 사항에는 프로젝트 코드를 성공적으로 업데이트하는 데 도움이 되는 "어떻게 해야 하나요?" 섹션이 포함되어 있습니다.

- [v4로 업그레이드](/ko/guides/upgrade-to/v4/)
- [v3로 업그레이드](/ko/guides/upgrade-to/v3/)
- [v2로 업그레이드](/ko/guides/upgrade-to/v2/)
- [v1로 업그레이드](/ko/guides/upgrade-to/v1/)

### 이전 문서 (관리되지 않음)

이전 버전의 Astro에 대한 문서는 유지 관리되지 않지만 정적 스냅샷으로 제공됩니다. 프로젝트를 업그레이드할 수 없지만 가이드와 참고 자료가 필요한 경우 이러한 버전의 문서를 사용하세요:

- [유지 관리되지 않는 v3.6.3 스냅샷](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/)
- [유지 관리되지 않는 v2.10.15 스냅샷](https://deploy-preview-4405--astro-docs-2.netlify.app/en/getting-started/)


## 유의적 버전 관리

Astro는 개발자가 릴리스에 버전 번호를 할당하는 방법을 결정하는 데 사용하는 일련의 규칙인 [유의적 버전 관리](https://semver.org/lang/ko/)를 최대한 준수하려고 노력합니다. 유의적 버전은 예측 가능한 패턴을 따라 사용자에게 한 버전에서 다음 버전으로 예상할 수 있는 변경 사항을 알려줍니다.

유의적 버전 관리에서는 소프트웨어 버전 번호에 'X.Y.Z'의 패턴을 적용합니다. 이 값은 **주(X)**, **부(Y)**, **수(Z)** 업데이트를 나타냅니다.

### 수버전 변경

수버전 변경은 가장 방해가 적은 변경입니다. 수버전은 Astro 사용 방식을 변경하지 않으며 업데이트할 때 자체 코드를 변경할 필요가 없습니다.

아스트로가 "수" 버전을 발행하면 마지막 숫자가 증가합니다. (예: `astro@4.3.14` -> `astro@4.3.15`)

수버전은 다음과 같은 이유로 릴리스될 수 있습니다:

- Astro의 기능을 변경하지 않는 내부 변경 사항입니다:
  - 리팩토링
  - 성능 개선
  - 테스트 커버리지의 증가 또는 변경
  - 명시된 문서 및 예상 동작과 일치
- 로깅 및 오류 메시지 개선.
- 실패한 릴리스 후 다시 릴리스.

수버전 변경에는 사용자가 기존의 의도하지 않았거나, 바람직하지 않은 동작을 이용하던 경우에도 **대부분의 버그 수정**이 포함됩니다.


### 부버전 변경

부버전 릴리스는 주로 사용해 볼 수 있는 새로운 기능과 개선 사항을 소개하지만 코드를 변경할 필요는 없습니다. 부버전 릴리스에서는 일부 기존 기능이 **사용 중단**(계속 작동하지만 향후 버전에서 삭제될 것으로 표시됨)될 수도 있으므로 최종 제거에 대비할 수 있는 기회를 제공합니다.

부버전 릴리스에는 다음과 같은 변경 사항이 포함되어 있습니다:

- 향후 주버전 릴리스에서 제거될 것이라는 경고와 함께 기존 기능/옵션의 **사용 중단**이 표시됩니다.
- 새로운 기능 도입.
- 통합 후크에 새로운 옵션 도입.
- 새로운 어댑터를 만드는 데 주로 사용되는 `astro/app`에 새로운 기능 도입.

부버전 릴리스에는 소규모 수버전 변경 사항도 동시에 포함될 수 있습니다.

### 주버전 변경

주버전 릴리스에는 최소한 일부 기존 코드에 대한 획기적인 변경 사항이 포함됩니다. 이러한 중요한 변경 사항은 항상 Astro의 ["vX로 업그레이드" 가이드](#업그레이드-가이드)에 문서화되어 있습니다.

주버전 릴리스에서는 내부 로직뿐만 아니라 의도된 동작과 사용법도 크게 변경할 수 있습니다. 문서는 최신 버전만 반영하도록 업데이트되며, 아직 업그레이드되지 않은 이전 프로젝트의 기록으로 **이전 문서의 유지 관리되지 않은 정적 스냅샷**을 사용할 수 있습니다.

주버전 릴리스에는 다음과 같은 변경 사항이 포함되어 있습니다:

- 이전에 더 이상 사용되지 않는 기능의 제거.
- 기존 기능의 변경.
- 통합 후크의 기존 옵션 변경.
- 새 어댑터를 만드는 데 사용되는 `astro/app`의 기존 옵션 및 기능 변경.

주버전 릴리스에는 일반적으로 부버전 릴리스나 수버전 릴리스에서 별도로 릴리스되는 일부 중요하지 않은 변경 사항과 개선 사항도 포함될 수 있습니다.

### 예외 사항

- **실험적 기능**. 유의적 버전 관리를 준수하지 않고 Astro 버전을 출시하면, Astro 개발자가 실험적 기능을 개발하는 동안 최대한 유연하게 탐색하고, 심지어 방향을 급격하게 변경할 수 있습니다. 따라서 이러한 기능의 동작은 부버전 및 수버전 변경으로 인해 중단될 수 있습니다.

  이러한 기능은 일반적으로 진행 중인 공개 [검토 요청(RFC) 3단계](https://github.com/withastro/roadmap#stage-3-rfc--development)와 함께 제공됩니다. 우리는 베타 사용자들에게 이러한 기능의 개발 방향에 도움이 될 수 있도록 업데이트를 확인하고, 토론에 대한 피드백을 조기에 남길 것으로 기대합니다.

  이러한 기능은 실험 기간이 끝나면 일반적인 유의적 버전 관리 계약을 따르게 됩니다.

- **문서 개선 사항**(예: 참조 및 오류 메시지). 이는 `docs` 리포지토리의 소스로부터 빌드됩니다. 이를 통해 문서 소스 콘텐츠가 기본 `astro` 리포지토리에 저장되어 있는 경우 Astro에서 문서 수정 및 개선 사항을 신속하게 업데이트할 수 있습니다.

### Node.js 지원 및 업그레이드 정책

#### 지원

- Astro는 [**최신 _Maintenance_ LTS** 버전의 Node.js](https://nodejs.org/en/about/previous-releases#release-schedule)를 지원합니다. 
- Astro는 [**현재 _Active_ LTS** 버전의 Node.js](https://nodejs.org/en/about/previous-releases#release-schedule)를 지원합니다. 
- Astro는 Node.js의 홀수 버전을 지원할 수 있습니다.

#### 업그레이드

다음 규칙은 Astro가 Node.js 버전에 대한 지원을 중단, 삭제 또는 추가할 수 있는 시기를 정의합니다.

- Node.js의 홀수 버전은 Node.js의 다음 짝수 버전이 게시될 때 더 이상 사용되지 않거나 삭제될 수 있습니다. 이 변경 사항은 Astro Core 팀이 결정한 대로 합당한 확장 지원 기간이 끝난 후 Astro의 **부** 릴리스에서 발생할 수 있습니다.
- Node.js의 최소 **_Maintenance_ LTS** (동일한 주버전 범위와 함께, 예를 들어 `v18.14.*`에서 `v18.20.*`로) 버전 업그레이드는 Astro의 **부** 릴리스에서 발생할 수 있습니다.
  - 보안 예외: **Astro에 영향을 미치는** Node.js의 보안 결함이 공개되어 수정되면 Core 팀은 **수** 릴리스에서 **_Maintenance_ LTS**의 최소 버전을 높일 수 있습니다.
- Node.js의 부 또는 주버전 업그레이드 (**Maintenance LTS 아님**)는 Astro의 주버전에서만 발생합니다.
  - 보안 예외: **Astro에 영향을 미치는** Node.js의 보안 결함이 공개되어 수정되면 Core 팀은 **부** 릴리스에서 최소 버전을 높일 수 있습니다.

### 연장된 유지 관리
 
Core 팀은 이전 주버전에 대해 **보안 수정을 위해서만** 연장된 유지 관리를 제공할 것입니다. 즉, 현재 주버전이 `v4.*`인 경우 코어 팀은 포트 보안 수정 사항을 지원하고 새로운 `v3.*` 릴리스를 발행할 것입니다.